Sketchup To Ogre Exporter  Version 1.2.0b9 - March 2010
Writter by Fabrizio Nunnari <fabrizio.nunnari@vrmmp.it>
(based on 1.0.1 Written by Kojack)


This is a ruby based script for SketchUp which can export 3D scenes to the Ogre rendering engine.
It is released under the LGPL.


Installation
------------

Along with this readme.txt, you should have received files called ogre_export_<version>.rb, ogre_export_config.rb and backface.rb. All 3 of those *.rb files should be placed in the SketchUp plugin directory. For example, this may be C:\Program Files\Google\Google SketchUp 7\Plugins.

On a Mac, copy it under:
/Library/Application Support/Google SketchUp [n]/SketchUp/plugins

Once these files are in the SketchUp plugin directory, you MUST edit the ogre_export_config.rb. It specifies where exported data will be placed, and other options. There is not an editing GUI for settings at this time.

It's ok to edit ogre_export_config.rb while SketchUp is running. The exporter reloads ogre_export_config.rb every time you start an export, so just edit the file and save and the changes will apply to the next export you do.



Usage
-----

There are 2 components within this package, A back face tool and an exporter. Both place menu items in the Tools menu.

Backface
--------
The back face tool allows easier handling of back faces. Sketchup allows backfaces as a valid surface, whereas 3D engines like Ogre default to hiding back faces to speed up rendering.

Select the "Highlight Backfaces" menu item to colour the back of every face to bright pink. This lets you easily spot which back faces are visible. Don't worry, the materials which were on the backfaces are preserved, and can be restored (keep reading...). Any bright pink surface you can see in your model will be completely invisible in Ogre.

Select the "Unhighlight Backfaces" menu item to restore the original materials to the back faces. Note: if you use "Highlight Backfaces" several times, any face which hasn't been unhighlighted will lose it's original texture (I'll fix that at some point).

Select the "Flip Backface" menu item to restore the original material to the selected face, and also swap the front and back faces (without changing the direction of the material. Sketchup has a build in tool to reverse the direction of a face, but it will swap which sides the materials are on too.



Exporter
--------
The exporter has a menu item: "Export Selection To Ogre Mesh". It exports the currently selected items.

Once you select the export menu item, you will be presented with a dialog asking for the export name. This is the start of the filename used for both meshes and materials. If you enter "test", then your output files will be called "test.mesh.xml" and "test.materials". Do not manually add the extensions, they are added automatically.

Once exporting is complete, a dialog will appear telling you how many triangles and submeshes were exported. All triangles with the same material are merged into a single submesh. There will be a material for each submesh. The less submeshes you have, the better the performance will be in ogre.

For further details about the exporter geometry open the Ruby Console before exporting.
For a damn-high detailed information during the export, uncomment the #print line in the debug_print procedure in the ogre_export_<version>.rb source.

See the ogre_export_config.rb file for help on which options you can specify. You can control what is exported, what scale to use, etc.

Notes
-----

- Materials with spaces in their name will have them replaced with underscores during export (but only in the exported files, the material in Sketchup isn't renamed). Other symbols may confuse Ogre's material system, so try to keep material names to basic alphanumeric characters.
- In Texture file names spaces will be replaced with underscores. Again, SketchUp Names will be untouched.
- Edges aren't exported. If your model relies on edges for showing detail, you won't see them in Ogre. This may be added in a later version.
- This tool was tested on SketchUp 6.4.112, OgreCommandLineTools 1.4.4, LexiView-1.0.7.
- Also tested on SketchUp 7.1, MacOS10.6 and WinXP. OgreCommandLineTools 1.6.5 on Mac and 1.6.3 on Win.
- This is my first ever Ruby script, so experienced Ruby coders will probably think it sucks. :)


Known Bugs and Limitations
--------------------------
For some transparent textures, the transparency is not automatically recognized. You must manually add the "scene_blend alpha_blend", "depth_check on" and "depth_write off" lines to the material pass. The problems is that the Material.has_alpha? method returns false for some transparent textures.
Another trick: In SketchUp put the Material opacity at 99%.
Some TIFF images do not save correctly. Export failure is notified via a Dialog. Export them from SketchUp and convert them into another format.


Bugs Reporting
--------------

If you find a model that you cannot export, or you find bugs, or an error message asks you to inform developers, then please report it to the author(s) following these simple rules:
1 - Insulate the exporting problem into the smallest 3D you can obtain. Even a single square. The smallest the polygon, the easier debug will be.
2 - Report the exact versions of: SketchUp, OgreCommandLineTools (if converting).
3 - Report which kind of Ogre viewer (e.g. Lexi, CEGUI) you are using and its version. If you use your own C++ code, report the Ogre version.


Development Notes (by fnunnari)
-------------------------------
Briefly: how the exporter works.
The exporter main procedure works in 5 stages:
1 - Recursively scans the geometry structure of selected entities. This will fill several structures that will be used later for export
2 - Renames what needs to be renamed: remove spaces from material and texture names, avoid name conflicts, put prefixes.
3 - Exports the geometry
4 - Exports the materials
5 - Exports the textures

The recursive "ogre_scan_geometry" procedure is quite complicated and deserves some comments.
Its is based on two assumptions:
1 - In SketchUp the geometry hierarchy is composed by intermediate Group or ComponentInstance nodes and leaf nodes of type Face. We are ignoring other types, such as Edges. In SketchUp, materials can be assigned to Faces as well to intermediate Nodes. When a material is found on an intermediate node, it is recursively applied to all the children that don't specify their own material.
2 - Texture loading and writing is done through the use of the TextureWriter class. It can be noticed that, for some models, SketchUp loads the same texture for the same material several times, and saves several distorted copies of the same texture. It seems that SketchUp computes different UV-mappings for the same texture. This yields to have several Ogre Materials (or better different texture variants) for a single SketchUp Material.

Given this two assumptions, the geometry scanner works roughly like this:
- We distinguish between SketchUp Materials and Ogre Materials, remembering that there can be several Ogre Materials associated to a SketchUp Material.
- Each time we encounter a Node or a Face with a new SketchUp Material, we create a new instance of OgreMaterial.
- We classify OgreMaterials in two categories: from_texture and from_color.
- When a new OgreMaterial has to be created, we try to load the texture used by the entity we are analyzing. If the texture loading (TextureWriter.load) returns 0, it uses no textures, otherwise, we memorize the handle of the texture.
- Each time we encounter an entity with a known SketchUp Material, we retrieve the Ogre Material previously created.
- If the material was created from a texture, we try (again) to load a texture for the current entity. The TextureWriter.load method will return either the same handle of a previously loaded texture or a new one. In the latter case, we create a new Ogre Material, associated with the same SketchUp Material.

During the export, we will have a submesh for each texture-variant that was created during the scan.
Of course, the number of textures and their occupied space might be greater than in the original model.


History
-------

by Kojack
1.0.0 - First release
1.0.1 - Materials inherited from groups / components

continued by fnunnari
1.2.x - Reworked geometry scanning and materials/textures handling
Detailed history in the exporter Ruby source
